@vscode/l10n

What is @vscode/l10n?

@vscode/l10n is a localization library designed to help developers internationalize their Visual Studio Code extensions. It provides tools to manage and use localized strings within extensions, making it easier to support multiple languages.

What are @vscode/l10n's main functionalities?

Loading Localized Strings

This feature allows you to load localized strings based on the user's locale. The code sample demonstrates how to configure the locale and messages, and then use the localized string in a Visual Studio Code extension.

const vscode = require('vscode');
const l10n = require('@vscode/l10n');

async function activate(context) {
  await l10n.config({
    locale: 'en',
    messages: {
      'hello': 'Hello, World!'
    }
  });

  const message = l10n.t('hello');
  vscode.window.showInformationMessage(message);
}

exports.activate = activate;

Dynamic Locale Switching

This feature allows dynamic switching of locales within the extension. The code sample shows how to switch from English to Spanish and update the localized string accordingly.

const vscode = require('vscode');
const l10n = require('@vscode/l10n');

async function activate(context) {
  await l10n.config({
    locale: 'en',
    messages: {
      'hello': 'Hello, World!'
    }
  });

  vscode.commands.registerCommand('extension.switchLocale', async () => {
    await l10n.config({
      locale: 'es',
      messages: {
        'hello': '¡Hola, Mundo!'
      }
    });
    const message = l10n.t('hello');
    vscode.window.showInformationMessage(message);
  });
}

exports.activate = activate;

Using Placeholders in Localized Strings

This feature supports placeholders in localized strings, allowing dynamic content to be inserted. The code sample demonstrates how to use a placeholder in a localized string and replace it with a variable.

const vscode = require('vscode');
const l10n = require('@vscode/l10n');

async function activate(context) {
  await l10n.config({
    locale: 'en',
    messages: {
      'greeting': 'Hello, {0}!'
    }
  });

  const name = 'John';
  const message = l10n.t('greeting', name);
  vscode.window.showInformationMessage(message);
}

exports.activate = activate;

Other packages similar to @vscode/l10n

i18next

i18next is a popular internationalization framework for JavaScript. It provides a comprehensive solution for managing translations and supports various backends for loading translations. Compared to @vscode/l10n, i18next is more general-purpose and can be used in a wide range of applications, not just Visual Studio Code extensions.

react-intl

react-intl is a library for internationalizing React applications. It provides components and APIs to format dates, numbers, and strings, and manage translations. While @vscode/l10n is specific to Visual Studio Code extensions, react-intl is tailored for React applications, offering a more integrated solution for that ecosystem.

polyglot

Polyglot is a lightweight library for internationalizing JavaScript applications. It focuses on simplicity and ease of use, providing basic functionality for managing translations and pluralization. Compared to @vscode/l10n, Polyglot is more minimalistic and can be used in various JavaScript environments.

README

@vscode/l10n

Library used for loading the translations into subprocesses of your extension. These usages also get picked up by l10n-dev string extraction tooling.

Note

You should NOT use this library in your extension's main process. The translations are loaded into the main process by VS Code itself.

Usage

import * as l10n from '@vscode/l10n';

// Load the translations for the current locale
l10n.config({
    contents: JSON.parse(process.env.BUNDLE_FROM_EXTENSION)
});
// or
l10n.config({
    fsPath: process.env.FSPATH_TO_BUNDLE_FROM_EXTENSION
});
// or (warning, this is async)
await l10n.config({
    uri: JSON.parse(process.env.BUNDLE_URI_FROM_EXTENSION)
});

// returns the translated string or the original string if no translation is available
l10n.t('Hello World');

// supports arguments just like the vscode API
l10n.t('Hello {0}', 'John');

// supports comments for translators
l10n.t({
    message: 'Hello {0}',
    args: ['John'],
    comment: ['This is a comment']
});

The input for l10n.conig pairs nicely with the bundle and uri properties on the l10n namespace that are provided by the VS Code API. You should send the value of one of these properties from your extension to your subprocess that is consuming @vscode/l10n.